fix(config): replace subagent model settings atomically instead of merging - #234

…ab (#235)

## Related Issue

No issue. Third step of the subagent routing work. Stacked on #234
(merge #234 first; this diff includes its commit until then).

## Problem

`GET /meta` flattened experimental flags to booleans. The Lab tab showed
the saved `[experimental]` value, so when
`PYTHINKER_CODE_EXPERIMENTAL_*` (or the master switch) decided a flag,
the switch and the runtime disagreed with no explanation.

## What changed

- `FlagService.explain()` carries two server-decided fields:
`externallyControlled` (`source` is `env` or `master-env`) and
`overridden` (a saved value exists and differs from the effective
value). Nothing is inferred in the UI.
- `GET /meta` adds `experimental_flag_states[]` (`id`, `enabled`,
`source`, `config_value?`, `default_enabled`, `externally_controlled`,
`overridden`) beside the existing boolean map (additive).
- Web: the meta client maps the list (`toAppExperimentalFlagStates`),
workspace state stores it on every `/meta` refresh,
`usePythinkerWebClient` exposes `experimentalFlagStates` /
`experimentalFlagState(id)`, and the Lab rows show `Environment
controlled` and `Saved setting overridden` chips independently. The
switch still edits the saved setting.
- klient `flags` contract mirrors the two fields (contract parity test).
- `dist-web` rebuilt from source.

Tests: core `explain()` matrix (env+config agree → controlled only; env
overrides config → both; master-env; config → neither); gateway `/meta`
three cases; web mapper unit test; workspace-state stores the list;
Settings chips each independently and none for `source=config`.

## Checklist

- [x] I have read the
[CONTRIBUTING](https://github.com/PyModel/pythinker-code/blob/main/CONTRIBUTING.md)
document.
- [ ] I have linked a related issue (external PRs: the issue must have a
maintainer's `/approve`).
- [x] I have added tests that prove my feature works.
- [x] Ran `gen-changesets` skill, or this PR needs no changeset.
- [x] Ran `gen-docs` skill, or this PR needs no doc update.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Lab settings now show when experimental options are controlled by the
environment or differ from saved settings.
* Experimental feature status is refreshed after configuration changes.
* **Bug Fixes**
* Prevented outdated server information from replacing newer settings
data.
  * Disabling the secondary-model pin now saves correctly.
* **Chores**
  * Updated the web application build and release metadata.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

…nt (#236)

## Related Issue

No issue. Fourth step of the subagent routing work. Stacked on #235
(merge #234 and #235 first; until then this diff includes their
commits).

## Problem

The subagent model configuration was validated only when a session
started, so any write could persist an unresolvable policy and the user
found out later. Several runtime readers consumed the legacy
`secondary_model` fields directly, and nothing let a client save the
policy without racing another writer.

## What changed

- `session/subagent/policy.ts`: `LegacySecondaryModelConfig` (disk /
legacy REST) is separated from `CanonicalSubagentModelPolicy` (`inherit
| default | pool | force`, zod discriminated union).
`normalizeLegacySecondaryModel` covers every legacy field combination
(16-row table test), persisted inherit is the absent section, canonical
values never carry legacy fields. `validateSubagentModelPolicy` is pure
and takes a `resolveModel` context; `prospectiveModelView` builds that
context from a previewed configuration. `subagentPolicyResourceVersion`
(strong hash over the canonical policy, `null` for the absent section),
`routingEnvironmentRevision` (ambient inputs only) and
`routeDecisionFingerprint` (request intent) are separate hashes.
- `ISubagentModelPolicyService` (App scope): `get()`, `getEffective()`
(effective policy is inherit while the feature is disabled, and its
source is then `default`), `set`/`clear` with an `expectedVersion` guard
(`config.version_conflict`), `prepareLegacyMutation(input, context?)`
for coordinators, `resolveRevision(caller)`.
- `IConfigService.previewReplaceSections(sections)`: the effective
configuration a replacement would yield (defaults, env bindings,
overlays such as the `PYTHINKER_MODEL_NAME` model, memory overrides)
with zero writes, zero events, zero registry mutation.
- `POST /config`: `secondary_model` goes through `prepareLegacyMutation`
against the prospective configuration of the same request, then one
`replaceSections()`. The B1 direct staging is gone. Provider discovery
routes its cascaded section through the same preparation.
- `GET/PUT/DELETE /config/subagent-model-policy` with a strong `ETag`
(`"subagent-policy-v1:<hash>"`, never weak) and `If-Match` → HTTP 412 +
`41201`. `DELETE` removes the section; legacy `POST /config` and
canonical `PUT` produce byte-identical files.
- Runtime readers in `configSection.ts` derive from the canonical
policy. An import-boundary test keeps legacy symbols inside the
adapter/policy service and asserts the section is written only by the
policy service or a prepared mutation.
- Existing gateway tests that persisted unknown model aliases now
configure those models first (validation at write time is the new
contract). API surface snapshot and config manifest updated.

Tests added: policy table + messages + round-trip + strict parsing;
validation matrix; prospective view; resource version stability (key
order, legacy spellings, absent section); revision/fingerprint
separation; service unit tests (set/clear/version
guard/effective/prepare/revision); `previewReplaceSections`
zero-side-effect test and a removal/swap prospective test; gateway
endpoint tests (ETag strong, 412 on PUT and DELETE, DELETE removes the
section, no-op PUT keeps the ETag, external file edit changes it, legacy
POST ≡ canonical PUT, feature-disabled effective inherit); `/config`
prospective-model and env-overlay tests.

## Checklist

- [x] I have read the
[CONTRIBUTING](https://github.com/PyModel/pythinker-code/blob/main/CONTRIBUTING.md)
document.
- [ ] I have linked a related issue (external PRs: the issue must have a
maintainer's `/approve`).
- [x] I have added tests that prove my feature works.
- [x] Ran `gen-changesets` skill, or this PR needs no changeset.
- [x] Ran `gen-docs` skill, or this PR needs no doc update.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added subagent model policy configuration with inherit, default, pool,
and force modes.
* Added API support to view, update, and clear policies, including
effective settings and version safeguards.
* Added detailed model validation, effort settings, and compatibility
with existing secondary-model configuration.
* **Bug Fixes**
* Prevented invalid model references from persisting during provider
refreshes.
* Removed unavailable models from secondary-model pools and cleared
dangling defaults.
* **Documentation**
* Added release metadata describing the new policy configuration
options.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

…ance (#237)

## Related Issue

No issue. Fifth step of the subagent routing work. Stacked on #236
(merge #234, #235, #236 first; until then this diff includes their
commits).

## Problem

Model selection for a new subagent lived in `planSpawn()` and again in
`resolveSubagentBinding()`, and nothing recorded why a child was bound
the way it was. A resumed child that kept an older model (created under
"main = Luna", resumed under "main = Sol") was indistinguishable from a
routing bug, and the Dynamic Workflow card had to guess.

## What changed

- `resolveSubagentModelRoute()` is the single binding authority (inherit
/ default / pool / force; `primary` override; force rejects any explicit
choice). `resolveSubagentBinding()` and the new
`SessionSubagentRoutingService` both delegate to it. `planSpawn()` is a
facade over the routing service; every plan carries `RoutingProvenance`
(`operation`, `profileSource`, `modelSource`, `policyMode`,
`policySource`, `featureSource`,
`resolvedFromRoutingEnvironmentRevision`, `routeDecisionFingerprint`).
- `SubagentBindingProvenance` is persisted once on the child (durable
agent event `subagent.binding_provenance.recorded` folded into a
replayable state key) when the child is created from a plan; forks
record `fork-inherit`. Resume reads it back: sources become
`resume-existing`, the original revision is kept, and the caller's
current `routingEnvironmentRevision` is reported alongside — never
written into the child.
- Live path: `SubagentTaskInfo`, the `subagent.spawned` event, REST
`/tasks`, the WS roster, and the session snapshot carry `routing` +
`current_routing_env_revision`; `packages/protocol` schemas and the web
client (`AppTask.routing`, `DynamicWorkflowMember`, card rows,
`keepLiveSubagents`) map them. Stable enum ids only; no display labels
on the wire.
- Durable path: the Dynamic Workflow result writes `<subagent … profile
model thinking profile_source model_source policy_mode policy_source
feature_source routing_env_revision route_decision started_at
completed_at>` through the existing attribute escaper;
`parseDynamicWorkflowResult` reads them and older results still parse.
- TUI: SDK types are additive/optional;
`agent-dynamic-workflow-progress` and `subagent-event-handler` compile
and their tests pass unchanged.
- `dist-web` rebuilt; state and wire manifests regenerated.

Tests: route matrix (inherit/default/pool/force × explicit/primary/none,
force rejects `primary`); routing service provenance for
spawn/pool/force/fork; two spawns share the environment revision and
differ in decision fingerprint; the mandatory Luna→Sol resume regression
(child stays on Luna, `resume-existing`, original revision A, current
revision B); provenance recorded exactly once per child for spawn and
fork; state fold + record guard; renderer attributes + escaping; gateway
task mapping and roster tracker; web projector, mappers, parser (new
attributes, old rows), card rows pass-through, task merge.

## Checklist

- [x] I have read the
[CONTRIBUTING](https://github.com/PyModel/pythinker-code/blob/main/CONTRIBUTING.md)
document.
- [ ] I have linked a related issue (external PRs: the issue must have a
maintainer's `/approve`).
- [x] I have added tests that prove my feature works.
- [x] Ran `gen-changesets` skill, or this PR needs no changeset.
- [x] Ran `gen-docs` skill, or this PR needs no doc update.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Subagent tasks and workflow results now display routing details,
selected profile/model sources, policy decisions, environment revisions,
and execution timestamps.
* Routing information is preserved across spawned, forked, background,
and resumed subagent runs.
* Server metadata now exposes effective experimental feature-flag
states.

* **Bug Fixes**
* Prevented routing metadata from being overwritten or lost when task
data is merged.
* Cleared stale suspension reasons when updated suspension events omit
them.
* Ensured secondary-model settings can be explicitly cleared when no
longer available.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

… card (#239)

## Related Issue

No issue. Sixth step of the subagent routing work. Stacked on #237
(merge #234 → #237 first; until then this diff includes their commits).

## Problem

The Dynamic Workflow card showed one shared model label and a flat
member list. A mixed workflow — resumed children that kept an older
model, a forced policy, a pool default — had no explanation, failures
were not prominent, and nothing said that a policy change only applies
to new subagents.

## What changed

- Header: the count once (`3 / 9`) plus a status pill. Body opens with a
routing line: `MAIN <model · effort>` and `SUBAGENTS` as `Inherit → …`,
`<model> · Override`, or `Mixed · N models` with a breakdown (`2 Sol ·
Max · 1 Luna · High`). Policy provenance (`Model policy: Saved
setting|Default`) and feature provenance (`Feature: Enabled by
environment|Saved setting|Default`) render on separate lines. A forced
policy offers a `Change in Settings` chip that opens Settings → Agent.
- Rows grouped by phase with severity-aware order (running with
failures: Failed, Suspended, Working, Queued, Completed, Cancelled;
running healthy: Working first; settled: Failed first, residual
Working/Queued kept visible); Failed/Suspended always expanded,
Completed collapsed while running with `Show ›`. Each row: name,
activity, `Profile · Model · Effort`, elapsed (`m:ss`, `now-startedAt`
live / `completedAt-startedAt` settled), a provenance word (`Inherited`,
`Pool`, `Forced`, `Forked`, `Resume existing`), and `Created under
earlier routing · Current main: <model>` when the row's environment
revision differs from the current one. The notice `Applies to new
subagents; N existing keep their model` is driven only by the
environment revision, never by model ids or decision fingerprints.
- Segmented progress: one cell per task up to 12 rows, proportional
grouped bar beyond; only the active row dot pulses. Sizes use the
existing tokens.
- Pure helpers (`groupDynamicWorkflowRows`,
`dynamicWorkflowRowElapsedMs`, `formatElapsed`) in
`dynamicWorkflowCardRows.ts`; `App.vue` provides `mainModelBinding` and
`openAgentSettings`; Settings accepts `initialTab: 'agent'`. `dist-web`
rebuilt.

Tests: grouping order/expansion/empty phases, both elapsed formulas and
formatting (`dynamic-workflow-card-rows.test.ts`); component: header
count once, cells at 9 vs grouped bar at 13, Failed-first only with
failures, MAIN/inherit/mixed + provenance words, policy and feature
lines independent, Override chip only for `policy-force` and opens
Settings, notice from revision mismatch only, meta + elapsed per row
(`dynamic-workflow-card.test.ts`).

## Checklist

- [x] I have read the
[CONTRIBUTING](https://github.com/PyModel/pythinker-code/blob/main/CONTRIBUTING.md)
document.
- [ ] I have linked a related issue (external PRs: the issue must have a
maintainer's `/approve`).
- [x] I have added tests that prove my feature works.
- [x] Ran `gen-changesets` skill, or this PR needs no changeset.
- [x] Ran `gen-docs` skill, or this PR needs no doc update.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Enhanced Dynamic Workflow cards with subagent details, routing
sources, provenance, model metadata, elapsed times, and revision
notices.
* Grouped workflow members by phase, showing failures first, with
collapsible sections and clearer progress indicators.
* Added settings for folding completed turns and consecutive tool-call
activity.
* Added clearer experimental-setting indicators and direct navigation to
agent settings.

* **Bug Fixes**
* Improved handling of overlapping configuration updates to prevent
stale information from being displayed.

* **Tests**
* Expanded coverage for workflow grouping, routing states, metadata,
progress, and elapsed-time displays.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->